<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="generator" content="pandoc">
  <meta name="author" content="by John MacFarlane">
  <meta name="author" content="Translated by Tzeng Yuxio">
  <title>Pandoc’s Markdown 語法中文翻譯</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link href="https://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css" rel="stylesheet">
  <link href="stylesheets/pandoc.css" rel="stylesheet">
  <style type="text/css">code{white-space: pre;}</style>
  <!--[if lt IE 9]>
    <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
  <![endif]-->
</head>
<body>
<!-- doc title / page header -->
<header>
<h1 class="title"><a href="http://pages.tzengyuxio.me/pandoc/">Pandoc’s Markdown 語法中文翻譯</a></h1>
<!--<h2 class="author">by John MacFarlane</h2>-->
<!--<h2 class="author">Translated by <a href="http://tzengyuxio.me">Tzeng Yuxio</a></h2>-->
</header>
<div class="container-fluid">
<div class="row-fluid">
<div class="span4">
<nav id="TOC" class="sidebar-nav sidebar-nav-fixed">
<ul>
<li><a href="#前言">前言</a></li>
<li><a href="#pandocs-markdown">Pandoc’s markdown</a><ul>
<li><a href="#哲學">哲學</a></li>
<li><a href="#段落">段落</a></li>
<li><a href="#標題">標題</a><ul>
<li><a href="#setext-風格標題">Setext 風格標題</a></li>
<li><a href="#atx-風格標題">Atx 風格標題</a></li>
<li><a href="#html-latex-與-context-的標題識別符">HTML, LaTeX 與 ConTeXt 的標題識別符</a></li>
</ul></li>
<li><a href="#區塊引言">區塊引言</a></li>
<li><a href="#字面代碼區塊">字面（代碼）區塊</a><ul>
<li><a href="#縮進代碼區塊">縮進代碼區塊</a></li>
<li><a href="#圍欄代碼區塊">圍欄代碼區塊</a></li>
</ul></li>
<li><a href="#行區塊">行區塊</a></li>
<li><a href="#清單">清單</a><ul>
<li><a href="#無序清單">無序清單</a></li>
<li><a href="#四個空白規則">四個空白規則</a></li>
<li><a href="#有序清單">有序清單</a></li>
<li><a href="#定義清單">定義清單</a></li>
<li><a href="#編號範例清單">編號範例清單</a></li>
<li><a href="#緊湊與寬鬆清單">緊湊與寬鬆清單</a></li>
<li><a href="#結束一個清單">結束一個清單</a></li>
</ul></li>
<li><a href="#分隔線">分隔線</a></li>
<li><a href="#表格">表格</a><ul>
<li><a href="#簡單表格">簡單表格</a></li>
<li><a href="#多行表格">多行表格</a></li>
<li><a href="#格框表格">格框表格</a></li>
<li><a href="#管線表格">管線表格</a></li>
</ul></li>
<li><a href="#文件標題區塊">文件標題區塊</a></li>
<li><a href="#反斜線跳脫字元">反斜線跳脫字元</a></li>
<li><a href="#智慧型標點符號">智慧型標點符號</a></li>
<li><a href="#行內格式">行內格式</a><ul>
<li><a href="#強調">強調</a></li>
<li><a href="#刪除線">刪除線</a></li>
<li><a href="#上標與下標">上標與下標</a></li>
<li><a href="#字面文字">字面文字</a></li>
</ul></li>
<li><a href="#數學">數學</a></li>
<li><a href="#raw-html">Raw HTML</a></li>
<li><a href="#raw-tex">Raw TeX</a></li>
<li><a href="#latex-巨集">LaTeX 巨集</a></li>
<li><a href="#連結">連結</a><ul>
<li><a href="#自動連結">自動連結</a></li>
<li><a href="#行內連結">行內連結</a></li>
<li><a href="#參考連結">參考連結</a></li>
<li><a href="#內部連結">內部連結</a></li>
</ul></li>
<li><a href="#圖片">圖片</a><ul>
<li><a href="#附上說明的圖片">附上說明的圖片</a></li>
</ul></li>
<li><a href="#腳註">腳註</a></li>
<li><a href="#引用">引用</a></li>
</ul></li>
</ul>
</nav>
</div>
<div class="span8">
<h2 id="前言"><a href="#前言">前言</a></h2>
<p>這份文件是 <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> 版本 Markdown 語法的中文翻譯。Pandoc 本身是由 <a href="http://johnmacfarlane.net/">John MacFarlane</a> 所開發的文件轉換工具，可以在 HTML, Markdown, PDF, TeX…等等格式之間進行轉換。有許多喜歡純文字編輯的人，利用 Pandoc 來進行論文的撰寫或投影片製作。但除了轉換的功能外，Pandoc 所定義的 Markdown 擴充語法也是這套工具的一大亮點，在 Pandoc 的官方使用說明文件中，光是其針對 Markdown 格式的擴充就佔了整整一半左右的篇幅。</p>
<p>本文件翻譯自 <a href="http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown">Pandoc - Pandoc User’s Guide</a> 中的 “Pandoc’s markdown” 一節。你可以看看<a href="https://raw.github.com/tzengyuxio/pages/gh-pages/pandoc/pandoc.markdown">這份文件的原始檔</a>、產生文件<a href="https://github.com/tzengyuxio/pages/blob/gh-pages/pandoc/pm-template.html5">所使用的 HTML 範本</a>，以及<a href="https://github.com/tzengyuxio/pages/blob/gh-pages/pandoc/convert.sh">轉換時的命令參數</a>。</p>
<p>以下翻譯開始。</p>
<hr />
<h1 id="pandocs-markdown"><a href="#pandocs-markdown">Pandoc’s markdown</a></h1>
<p>與 John Gruber 的 原始 <a href="http://daringfireball.net/projects/markdown/">markdown</a> 相比，Pandoc 版本的 markdown 在語法上有額外的擴充與些許的修正。這份文件解釋了這些語法，並指出其與原始 markdown 的差異所在。除非特別提到，不然這些差異均可藉由使用 <code>markdown_strict</code> 而非 <code>markdown</code> 的格式來關閉。單獨一項擴充也可透過 <code>+EXTENSION</code> 或 <code>-EXTENSION</code> 的方式來開啟或關閉。例如，<code>markdown_strict+footnotes</code> 表示加上腳註擴充的原始 markdown，而 <code>markdown-footnotes-pipe_tables</code> 則是拿掉了腳註與管線表格擴充的 pandoc markdown。</p>
<h2 id="哲學"><a href="#哲學">哲學</a></h2>
<p>Markdown 是針對易於書寫與閱讀的目標而設計的，特別是在易於閱讀這點上尤為重要：</p>
<blockquote>
<p>一份 Markdown 格式的文件應該要能以純文字形式直接發表，並且一眼看過去不存在任何標記用的標籤或格式指令。 <small><a href="http://daringfireball.net/projects/markdown/syntax#philosophy">John Gruber</a></small></p>
</blockquote>
<p>這項原則同樣也是 pandoc 在制訂表格、腳註以及其他擴充的語法時，所依循的規範。</p>
<p>然而，pandoc 的目標與原始 markdown 的最初目標有著方向性的不同。在 markdown 原本的設計中，HTML 是其主要輸出對象；然而 pandoc 則是針對多種輸出格式而設計。因此，雖然 pandoc 同樣也允許直接嵌入 HTML 標籤，但並不鼓勵這樣的作法，取而代之的是 pandoc 提供了許多非 HTML 的方式，來讓使用者輸入像是定義清單、表格、數學公式以及腳註等諸如此類的重要文件元素。</p>
<h2 id="段落"><a href="#段落">段落</a></h2>
<p>一個段落指的是一行以上的文字，跟在一行以上的空白行之後。換行字元會被當作是空白處理，因此你可以依自己喜好排列段落文字。如果你需要強制換行，在行尾放上兩個以上的空白字元即可。</p>
<p><strong>Extension: <code>escaped_line_breaks</code></strong></p>
<p>一個反斜線後跟著一個換行字元，同樣也有強制換行的效果。</p>
<h2 id="標題"><a href="#標題">標題</a></h2>
<p>有兩種不同形式的標題語法，Setext 以及 atx。</p>
<h3 id="setext-風格標題"><a href="#setext-風格標題">Setext 風格標題</a></h3>
<p>Setext 風格的標題是由一行文字底下接著一行 <code>=</code> 符號（用於一階標題）或 <code>-</code> 符號（用於二階標題）所構成：</p>
<pre><code>A level-one header
==================

A level-two header
------------------</code></pre>
<p>標題的文字可以包含行內格式，例如強調（見下方 <a href="#行內格式">行內格式</a> 一節）。</p>
<h3 id="atx-風格標題"><a href="#atx-風格標題">Atx 風格標題</a></h3>
<p>Atx 風格的標題是由一到六個 <code>#</code> 符號以及一行文字所組成，你可以在文字後面加上任意數量的 <code>#</code> 符號。由行首起算的 <code>#</code> 符號數量決定了標題的階層：</p>
<pre><code>## A level-two header

### A level-three header ###</code></pre>
<p>如同 setext 風格標題，這裡的標題文字同樣可包含行內格式：</p>
<pre><code># A level-one header with a [link](/url) and *emphasis*</code></pre>
<p><strong>Extension: <code>blank_before_header</code></strong></p>
<p>原始 markdown 語法在標題之前並不需要預留空白行。Pandoc 則需要（除非標題位於文件最開始的地方）。這是因為以 <code>#</code> 符號開頭的情況在一般文字段落中相當常見，這會導致非預期的標題。例如下面的例子：</p>
<pre><code>I like several of their flavors of ice cream:
#22, for example, and #5.</code></pre>
<h3 id="html-latex-與-context-的標題識別符"><a href="#html-latex-與-context-的標題識別符">HTML, LaTeX 與 ConTeXt 的標題識別符</a></h3>
<p><strong>Extension: <code>header_attributes</code></strong></p>
<p>在標題文字所在行的行尾，可以使用以下語法為標題加上屬性：</p>
<pre><code>{#identifier .class .class key=value key=value}</code></pre>
<p>雖然這個語法也包含加入類別 (class) 以及鍵／值形式的屬性 (attribute)，但目前只有識別符 (identifier/ID) 在輸出時有實際作用（且只在部分格式的輸出，包括：HTML, LaTeX, ConTeXt, Textile, AsciiDoc）。舉例來說，下面是將標題加上 <code>foo</code> 識別符的幾種方法：</p>
<pre><code># My header {#foo}

## My header ##    {#foo}

My other header   {#foo}
---------------</code></pre>
<p>（此語法與 <a href="http://www.michelf.com/projects/php-markdown/extra/">PHP Markdown Extra</a> 相容。）</p>
<p>具有 <code>unnumbered</code> 類別的標題將不會被編號，即使 <code>--number-sections</code> 的選項是開啟的。單一連字符號 (<code>-</code>) 等同於 <code>.unnumbered</code>，且更適用於非英文文件中。因此，</p>
<pre><code># My header {-}</code></pre>
<p>與下面這行是等價的</p>
<pre><code># My header {.unnumbered}</code></pre>
<p><strong>Extension: <code>auto_identifiers</code></strong></p>
<p>沒有明確指定 ID（識別符）的標題將會依據其標題文字，自動指派一個獨一無二的 ID。由標題文字推導 ID 的規則如下：</p>
<ul>
<li>移除所有格式，連結等。</li>
<li>移除所有標點符號，除了底線、連字符號與句號。</li>
<li>以連字符號取代所有空白與換行字元。</li>
<li>將所有英文字母轉為小寫。</li>
<li>移除第一個字元前的所有內容（ID 不能以數字或標點符號開頭）。</li>
<li>如果剩下為空字串，則使用 <code>section</code> 作為 ID。</li>
</ul>
<p>以下是一些範例，</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Header</th>
<th style="text-align: left;">Identifier</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Header identifiers in HTML</td>
<td style="text-align: left;"><code>header-identifiers-in-html</code></td>
</tr>
<tr class="even">
<td style="text-align: left;"><em>Dogs</em>?–in <em>my</em> house?</td>
<td style="text-align: left;"><code>dogs--in-my-house</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">[HTML], [S5], or [RTF]?</td>
<td style="text-align: left;"><code>html-s5-or-rtf</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">3. Applications</td>
<td style="text-align: left;"><code>applications</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">33</td>
<td style="text-align: left;"><code>section</code></td>
</tr>
</tbody>
</table>
<p>在大多數情況下，這些規則應該讓人能夠直接從標題文字推導出 ID。唯一的例外是當有多個標題具有同樣文字的情況；在這情況下，第一個標題的 ID 仍舊是透過以上規則推導而得；第二個則是在同樣 ID 後加上 <code>-1</code>；第三個加上 <code>-2</code>；以此類推。</p>
<p>在開啟 <code>--toc|--table-of-contents</code> 的選項時，這些 ID 是用來產生目錄 (Table of Contents) 所需的頁面連結。此外，這些 ID 也提供了一個簡便的方式來輸入跳到指定章節的連結。一個以 ID 產生的連結，其使用的語法看起來就像下面的例子：</p>
<pre><code>See the section on
[header identifiers](#header-identifiers-in-html-latex-and-context).</code></pre>
<p>然而要注意的一點是，只有在以 HTML、LaTeX 與 ConTeXt 格式輸出時，才能以這種方式產生對應的章節連結。</p>
<p>如果指定了 <code>--section-divs</code> 選項，則每一個小節都會以 <code>div</code> 標籤包住（或是 <code>section</code> 標籤，如果有指定 <code>--html5</code> 選項的話），並且 ID 會被附加在用來包住小節的 <code>&lt;div&gt;</code>（或是 <code>&lt;section&gt;</code>）標籤，而非附加在標題上。這使得整個小節都可以透過 javascript 來操作，或是採用不同的 CSS 設定。</p>
<p><strong>Extension: <code>implicit_header_references</code></strong></p>
<p>Pandoc 假設每個標題都定義了其參考連結，因此，相較於以下的連結語法</p>
<pre><code>[header identifiers](#header-identifiers-in-html)</code></pre>
<p>你也可以單純只寫</p>
<pre><code>[header identifiers]</code></pre>
<p>或</p>
<pre><code>[header identifiers][]</code></pre>
<p>或</p>
<pre><code>[the section on header identifiers][header identifiers]</code></pre>
<p>如果有多個標題具有同樣文字，對應的參考只會連結到第一個符合的標題，這時若要連結到其他符合的標題，就必須以先前提到的方式，明確指定連結到該標題的 ID。</p>
<p>與其他一般參考連結不同的是，這些參考連結是大小寫有別的。</p>
<p>注意：如果你有明確定義了任何一個標題的標示符，那麼選項 <code>implicit_header_references</code> 就沒有作用。</p>
<h2 id="區塊引言"><a href="#區塊引言">區塊引言</a></h2>
<p>Markdown 使用 email 的習慣來建立引言區塊。一個引言區塊可以由一或多個段落或其他的區塊元素（如清單或標題）組成，並且其行首均是由一個 <code>&gt;</code> 符號加上一個空白作為開頭。（<code>&gt;</code> 符號不一定要位在該行最左邊，但也不能縮進超過三個空白）。</p>
<pre><code>&gt; This is a block quote. This
&gt; paragraph has two lines.
&gt;
&gt; 1. This is a list inside a block quote.
&gt; 2. Second item.</code></pre>
<p>有一個「偷懶」的形式：你只需要在引言區塊的第一行行首輸入 <code>&gt;</code> 即可，後面的行首可以省略符號：</p>
<pre><code>&gt; This is a block quote. This
paragraph has two lines.

&gt; 1. This is a list inside a block quote.
2. Second item.</code></pre>
<p>由於區塊引言可包含其他區塊元素，而區塊引言本身也是區塊元素，所以，引言是可以嵌套入其他引言的。</p>
<pre><code>&gt; This is a block quote.
&gt;
&gt; &gt; A block quote within a block quote.</code></pre>
<p><strong>Extension: <code>blank_before_blockquote</code></strong></p>
<p>原始 markdown 語法在區塊引言之前並不需要預留空白行。Pandoc 則需要（除非區塊引言位於文件最開始的地方）。這是因為以 <code>&gt;</code> 符號開頭的情況在一般文字段落中相當常見（也許由於斷行所致），這會導致非預期的格式。因此，除非是指定為 <code>markdown_strict</code> 格式，不然以下的語法在 pandoc 中將不會產生出嵌套區塊引言：</p>
<pre><code>&gt; This is a block quote.
&gt;&gt; Nested.</code></pre>
<h2 id="字面代碼區塊"><a href="#字面代碼區塊">字面（代碼）區塊</a></h2>
<h3 id="縮進代碼區塊"><a href="#縮進代碼區塊">縮進代碼區塊</a></h3>
<p>一段以四個空白（或一個 tab）縮進的文字區塊會被視為字面區塊 (Verbatim Block)：換句話說，特殊字元並不會轉換為任何格式，單純只以字面形式呈現，而所有的空白與換行也都會被保留。例如，</p>
<pre><code>    if (a &gt; 3) {
      moveShip(5 * gravity, DOWN);
    }</code></pre>
<p>位於行首的縮排（四個空白或一個 tab）並不會被視為字面區塊的一部分，因此在輸出時會被移除掉。</p>
<p>注意：在字面文字之間的空白行並不需要也以四個空白字元做開頭。</p>
<h3 id="圍欄代碼區塊"><a href="#圍欄代碼區塊">圍欄代碼區塊</a></h3>
<p><strong>Extension: <code>fenced_code_blocks</code></strong></p>
<p>除了標準的縮進代碼區塊外，Pandoc 也支援了<strong>圍欄</strong> (<em>fenced</em>) 代碼區塊的語法。這區塊需以包含三個以上波浪線 (<code>~</code>) 或反引號 (<code>`</code>) 的一行作為開始，並以同樣符號且至少同樣長度的一行作為結束。所有介於開始與結束之間的文字行都會視為代碼。不需要額外的縮進：</p>
<pre><code>~~~~~~~
if (a &gt; 3) {
  moveShip(5 * gravity, DOWN);
}
~~~~~~~</code></pre>
<p>如同一般的代碼區塊，圍欄代碼區塊與其前後的文字之間必須以空白行作間隔。</p>
<p>如果代碼本身也包含了一整行的波浪線或反引號，那麼只要在區塊首尾處使用更長的波浪線或反引號即可：</p>
<pre><code>~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~</code></pre>
<p>你也可以選擇性地使用以下語法附加屬性到代碼區塊上：</p>
<pre><code>~~~~ {#mycode .haskell .numberLines startFrom=&quot;100&quot;}
qsort []     = []
qsort (x:xs) = qsort (filter (&lt; x) xs) ++ [x] ++
               qsort (filter (&gt;= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code></pre>
<p>這裡的 <code>mycode</code> 為 ID，<code>haskell</code> 與 <code>numberLines</code> 是類別，而 <code>startsFrom</code> 則是值為 <code>100</code> 的屬性。有些輸出格式可以利用這些資訊來作語法高亮。目前有使用到這些資訊的輸出格式僅有 HTML 與 LaTeX。如果指定的輸出格式及語言類別有支援語法高亮，那麼上面那段代碼區塊將會以高亮並帶有行號的方式呈現。（要查詢支援的程式語言清單，可在命令列輸入 <code>pandoc --version</code>。）反之若無支援，則上面那段代碼區塊則會以下面的形式呈現：</p>
<pre><code>&lt;pre id=&quot;mycode&quot; class=&quot;haskell numberLines&quot; startFrom=&quot;100&quot;&gt;
  &lt;code&gt;
  ...
  &lt;/code&gt;
&lt;/pre&gt;</code></pre>
<p>下面這個是針對代碼區塊只有指定程式語言屬性的簡便形式：</p>
<pre><code>```haskell
qsort [] = []
```</code></pre>
<p>這與下面這行的效果是相同的：</p>
<pre><code>``` {.haskell}
qsort [] = []
```</code></pre>
<p>要取消所有語法高亮，使用 <code>--no-highlight</code> 選項。要設定語法高亮的配色，則使用 <code>--highlight-style</code>。</p>
<h2 id="行區塊"><a href="#行區塊">行區塊</a></h2>
<p><strong>Extension: <code>line_blocks</code></strong></p>
<p>行區塊是一連串以豎線 (<code>|</code>) 加上一個空格所構成的連續行。行與行間的區隔在輸出時將會以原樣保留，行首的空白字元數目也一樣會被保留；反之，這些行將會以 markdown 的格式處理。這個語法在輸入詩句或地址時很有幫助。</p>
<pre><code>| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I&#39;ve seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718</code></pre>
<p>如果有需要的話，書寫時也可以將完整一行拆成多行，但後續行必須以空白作為開始。下面範例的前兩行在輸出時會被視為一整行：</p>
<pre><code>| The Right Honorable Most Venerable and Righteous Samuel L.
  Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718</code></pre>
<p>這是從 <a href="http://docutils.sourceforge.net/docs/ref/rst/introduction.html">reStructuredText</a> 借來的語法。</p>
<h2 id="清單"><a href="#清單">清單</a></h2>
<h3 id="無序清單"><a href="#無序清單">無序清單</a></h3>
<p>無序清單是以項目符號作列舉的清單。每條項目都以項目符號 (<code>*</code>, <code>+</code> 或 <code>-</code>) 作開頭。下面是個簡單的例子：</p>
<pre><code>* one
* two
* three</code></pre>
<p>這會產生一個「緊湊」清單。如果你想要一個「寬鬆」清單，也就是說以段落格式處理每個項目內的文字內容，那麼只要在每個項目間加上空白行即可：</p>
<pre><code>* one

* two

* three</code></pre>
<p>項目符號不能直接從行首最左邊處輸入，而必須以一至三個空白字元作縮進。項目符號後必須跟著一個空白字元。</p>
<p>清單項目中的接續行，若與該項目的第一行文字對齊（在項目符號之後），看上去會較為美觀：</p>
<pre><code>* here is my first
  list item.
* and my second.</code></pre>
<p>但 markdown 也允許以下「偷懶」的格式：</p>
<pre><code>* here is my first
list item.
* and my second.</code></pre>
<h3 id="四個空白規則"><a href="#四個空白規則">四個空白規則</a></h3>
<p>一個清單項目可以包含多個段落以及其他區塊等級的內容。然而，後續的段落必須接在空白行之後，並且以四個空白或一個 tab 作縮進。因此，如果項目裡第一個段落與後面段落對齊的話（也就是項目符號前置入兩個空白），看上去會比較整齊美觀：</p>
<pre><code>  * First paragraph.

    Continued.

  * Second paragraph. With a code block, which must be indented
    eight spaces:

        { code }</code></pre>
<p>清單項目也可以包含其他清單。在這情況下前置的空白行是可有可無的。嵌套清單必須以四個空白或一個 tab 作縮進：</p>
<pre><code>* fruits
    + apples
        - macintosh
        - red delicious
    + pears
    + peaches
* vegetables
    + brocolli
    + chard</code></pre>
<p>上一節提到，markdown 允許你以「偷懶」的方式書寫，項目的接續行可以不和第一行對齊。不過，如果一個清單項目中包含了多個段落或是其他區塊元素，那麼每個元素的第一行都必須縮進對齊。</p>
<pre><code>+ A lazy, lazy, list
item.

+ Another one; this looks
bad but is legal.

    Second paragraph of second
list item.</code></pre>
<p><strong>注意：</strong>儘管針對接續段落的「四個空白規則」是出自於官方的 <a href="http://daringfireball.net/projects/markdown/syntax#list">markdown syntax guide</a>，但是作為對應參考用的 <code>Markdown.pl</code> 實作版本中並未遵循此一規則。所以當輸入時若接續段落的縮進少於四個空白時，pandoc 所輸出的結果會與 <code>Markdown.pl</code> 的輸出有所出入。</p>
<p>在 <a href="http://daringfireball.net/projects/markdown/syntax#list">markdown syntax guide</a> 中並未明確表示「四個空白規則」是否一體適用於 <strong>所有</strong> 位於清單項目裡的區塊元素上；規範文件中只提及了段落與代碼區塊。但文件暗示了此規則適用於所有區塊等級的內容（包含嵌套清單），並且 pandoc 以此方向進行解讀與實作。</p>
<h3 id="有序清單"><a href="#有序清單">有序清單</a></h3>
<p>有序清單與無序清單相類似，唯一的差別在於清單項目是以列舉編號作開頭，而不是項目符號。</p>
<p>在原始 markdown 中，列舉編號是阿拉伯數字後面接著一個句點與空白。數字本身代表的數值會被忽略，因此下面兩個清單並無差別：</p>
<pre><code>1.  one
2.  two
3.  three</code></pre>
<p>上下兩個清單的輸出是相同的。</p>
<pre><code>5.  one
7.  two
1.  three</code></pre>
<p><strong>Extension: <code>fancy_lists</code></strong></p>
<p>與原始 markdown 不同的是，Pandoc 除了使用阿拉伯數字作為有序清單的編號外，也可以使用大寫或小寫的英文字母，以及羅馬數字。清單標記可以用括號包住，也可以單獨一個右括號，抑或是句號。如果清單標記是大寫字母接著一個句號，句號後請使用至少兩個空白字元。<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a></p>
<p><strong>Extension: <code>startnum</code></strong></p>
<p>除了清單標記外，Pandoc 也能判讀清單的起始編號，這兩項資訊都會保留於輸出格式中。舉例來說，下面的輸入可以產生一個從編號 9 開始，以單括號為編號標記的清單，底下還跟著一個小寫羅馬數字的子清單：</p>
<pre><code> 9)  Ninth
10)  Tenth
11)  Eleventh
       i. subone
      ii. subtwo
     iii. subthree</code></pre>
<p>當遇到不同形式的清單標記時，Pandoc 會重新開始一個新的清單。所以，以下的輸入會產生三份清單：</p>
<pre><code>(2) Two
(5) Three
1.  Four
*   Five</code></pre>
<p>如果需要預設的有序清單標記符號，可以使用 <code>#.</code>：</p>
<pre><code>#.  one
#.  two
#.  three</code></pre>
<h3 id="定義清單"><a href="#定義清單">定義清單</a></h3>
<p><strong>Extension: <code>definition_lists</code></strong></p>
<p>Pandoc 支援定義清單，其語法的靈感來自於 <a href="http://www.michelf.com/projects/php-markdown/extra/">PHP Markdown Extra</a> 以及 <a href="http://docutils.sourceforge.net/docs/ref/rst/introduction.html">reStructuredText</a>：<a href="#fn2" class="footnoteRef" id="fnref2"><sup>2</sup></a></p>
<pre><code>Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.</code></pre>
<p>每個專有名詞 (term) 都必須單獨存在於一行，後面可以接著一個空白行，也可以省略，但一定要接上一或多筆定義內容。一筆定義需由一個冒號或波浪線作開頭，可以接上一或兩個空白作為縮進。定義本身的內容主體（包括接在冒號或波浪線後的第一行）應該以四個空白縮進。一個專有名詞可以有多個定義，而每個定義可以包含一或多個區塊元素（段落、代碼區塊、清單等），每個區塊元素都要縮進四個空白或一個 tab。</p>
<p>如果你在定義內容後面留下空白行（如同上面的範例），那麼該段定義會被當作段落處理。在某些輸出格式中，這意謂著成對的專有名詞與定義內容間會有較大的空白間距。在定義與定義之間，以及定義與下個專有名詞間不要留空白行，即可產生一個比較緊湊的定義清單：</p>
<pre><code>Term 1
  ~ Definition 1
Term 2
  ~ Definition 2a
  ~ Definition 2b</code></pre>
<h3 id="編號範例清單"><a href="#編號範例清單">編號範例清單</a></h3>
<p><strong>Extension: <code>example_lists</code></strong></p>
<p>這個特別的清單標記 <code>@</code> 可以用來產生連續編號的範例清單。清單中第一個以 <code>@</code> 標記的項目會被編號為 ‘1’，接著編號為 ‘2’，依此類推，直到文件結束。範例項目的編號不會侷限於單一清單中，而是文件中所有以 <code>@</code> 為標記的項目均會次序遞增其編號，直到最後一個。舉例如下：</p>
<pre><code>(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).</code></pre>
<p>編號範例可以加上標籤，並且在文件的其他地方作參照：</p>
<pre><code>(@good)  This is a good example.

As (@good) illustrates, ...</code></pre>
<p>標籤可以是由任何英文字母、底線或是連字符號所組成的字串。</p>
<h3 id="緊湊與寬鬆清單"><a href="#緊湊與寬鬆清單">緊湊與寬鬆清單</a></h3>
<p>在與清單相關的「邊界處理」上，Pandoc 與 <code>Markdown.pl</code> 有著不同的處理結果。考慮如下代碼：</p>
<pre><code>+   First
+   Second:
    -   Fee
    -   Fie
    -   Foe

+   Third</code></pre>
<p>Pandoc 會將以上清單轉換為「緊湊清單」（在 “First”, “Second” 或 “Third” 之中沒有 <code>&lt;p&gt;</code> 標籤），而 markdown 則會在 “Second” 與 “Third” （但不包含 “First”）裡面置入 <code>&lt;p&gt;</code> 標籤，這是因為 “Third” 之前的空白行而造成的結果。Pandoc 依循著一個簡單規則：如果文字後面跟著空白行，那麼就會被視為段落。既然 “Second” 後面是跟著一個清單，而非空白行，那麼就不會被視為段落了。至於子清單的後面是不是跟著空白行，那就無關緊要了。（注意：即使是設定為 <code>markdown_strict</code> 格式，Pandoc 仍是依以上方式處理清單項目是否為段落的判定。這個處理方式與 markdown 官方語法規範裡的描述一致，然而卻與 <code>Markdown.pl</code> 的處理不同。）</p>
<h3 id="結束一個清單"><a href="#結束一個清單">結束一個清單</a></h3>
<p>如果你在清單之後放入一個縮排的代碼區塊，會有什麼結果？</p>
<pre><code>-   item one
-   item two

    { my code block }</code></pre>
<p>問題大了！這邊 pandoc（其他的 markdown 實作也是如此）會將 <code>{ my code block }</code> 視為 <code>item two</code> 這個清單項目的第二個段落來處理，而不會將其視為一個代碼區塊。</p>
<p>要在 <code>item two</code> 之後「切斷」清單，你可以插入一些沒有縮排、輸出時也不可見的內容，例如 HTML 的註解：</p>
<pre><code>-   item one
-   item two

&lt;!-- end of list --&gt;

    { my code block }</code></pre>
<p>當你想要兩個各自獨立的清單，而非一個大且連續的清單時，也可以運用同樣的技巧：</p>
<pre><code>1.  one
2.  two
3.  three

&lt;!-- --&gt;

1.  uno
2.  dos
3.  tres</code></pre>
<h2 id="分隔線"><a href="#分隔線">分隔線</a></h2>
<p>一行中若包含三個以上的 <code>*</code>, <code>-</code> 或 <code>_</code> 符號（中間可以以空白字元分隔），則會產生一條分隔線：</p>
<pre><code>*  *  *  *

---------------</code></pre>
<h2 id="表格"><a href="#表格">表格</a></h2>
<p>有四種表格的形式可以使用。前三種適用於等寬字型的編輯環境，例如 Courier。第四種則不需要直行的對齊，因此可以在比例字型的環境下使用。</p>
<h3 id="簡單表格"><a href="#簡單表格">簡單表格</a></h3>
<p><strong>Extension: <code>simple_tables</code>, <code>table_captions</code></strong></p>
<p>簡單表格看起來像這樣子：</p>
<pre><code>  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table:  Demonstration of simple table syntax.</code></pre>
<p>表頭與資料列分別以一行為單位。直行的對齊則依照表頭的文字和其底下虛線的相對位置來決定：<a href="#fn3" class="footnoteRef" id="fnref3"><sup>3</sup></a></p>
<ul>
<li>如果虛線與表頭文字的右側有切齊，而左側比表頭文字還長，則該直行為靠右對齊。</li>
<li>如果虛線與表頭文字的左側有切齊，而右側比表頭文字還長，則該直行為靠左對齊。</li>
<li>如果虛線的兩側都比表頭文字長，則該直行為置中對齊。</li>
<li>如果虛線與表頭文字的兩側都有切齊，則會套用預設的對齊方式（在大多數情況下，這將會是靠左對齊）。</li>
</ul>
<p>表格底下必須接著一個空白行，或是一行虛線後再一個空白行。表格標題為可選的（上面的範例中有出現）。標題需是一個以 <code>Table:</code> （或單純只有 <code>:</code>）開頭作為前綴的段落，輸出時前綴的這部份會被去除掉。表格標題可以放在表格之前或之後。</p>
<p>表頭也可以省略，在省略表頭的情況下，表格下方必須加上一行虛線以清楚標明表格的範圍。例如：</p>
<pre><code>-------     ------ ----------   -------
     12     12        12             12
    123     123       123           123
      1     1          1              1
-------     ------ ----------   -------</code></pre>
<p>當省略表頭時，直行的對齊會以表格內容的第一行資料列決定。所以，以上面的表格為例，各直行的對齊依序會是靠右、靠左、置中以及靠右對齊。</p>
<h3 id="多行表格"><a href="#多行表格">多行表格</a></h3>
<p><strong>Extension: <code>multiline_tables</code>, <code>table_captions</code></strong></p>
<p>多行表格允許表頭與表格資料格的文字能以複數行呈現（但不支援橫跨多欄或縱跨多列的資料格）。以下為範例：</p>
<pre><code>-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here&#39;s another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: Here&#39;s the caption. It, too, may span
multiple lines.</code></pre>
<p>看起來很像簡單表格，但兩者間有以下差別：</p>
<ul>
<li>在表頭文字之前，必須以一列虛線作為開頭（除非有省略表頭）。</li>
<li>必須以一列虛線作為表格結尾，之後接一個空白行。</li>
<li>資料列與資料列之間以空白行隔開。</li>
</ul>
<p>在多行表格中，表格分析器會計算各直行的欄寬，並在輸出時盡可能維持各直行在原始文件中的相對比例。因此，要是你覺得某些欄位在輸出時不夠寬，你可以在 markdown 的原始檔中加寬一點。</p>
<p>和簡單表格一樣，表頭在多行表格中也是可以省略的：</p>
<pre><code>----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here&#39;s another one. Note
                                    the blank line between
                                    rows.
----------- ------- --------------- -------------------------

: Here&#39;s a multiline table without headers.</code></pre>
<p>多行表格中可以單只包含一個資料列，但該資料列之後必須接著一個空白行（然後才是標示表格結尾的一行虛線）。如果沒有此空白行，此表格將會被解讀成簡單表格。</p>
<h3 id="格框表格"><a href="#格框表格">格框表格</a></h3>
<p><strong>Extension: <code>grid_tables</code>, <code>table_captions</code></strong></p>
<p>格框表格看起來像這樣：</p>
<pre><code>: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+</code></pre>
<p>以 <code>=</code> 串成的一行區分了表頭與表格本體，這在沒有表頭的表格中也是可以省略的。在格框表格中的資料格可以包含任意的區塊元素（複數段落、代碼區塊、清單等等）。不支援對齊，也不支援橫跨多欄或縱跨多列的資料格。格框表格可以在 <a href="http://table.sourceforge.net/">Emacs table mode</a> 下輕鬆建立。</p>
<h3 id="管線表格"><a href="#管線表格">管線表格</a></h3>
<p><strong>Extension: <code>pipe_tables</code>, <code>table_captions</code></strong></p>
<p>管線表格看起來像這樣：</p>
<pre><code>| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of simple table syntax.</code></pre>
<p>這個語法與 <a href="http://michelf.ca/projects/php-markdown/extra/#table">PHP markdown extra 中的表格語法</a> 相同。開始與結尾的管線字元是可選的，但各直行間則必須以管線區隔。上面範例中的冒號表明了對齊方式。表頭可以省略，但表頭下的水平虛線必須保留，因為虛線上定義了資料欄的對齊方式。</p>
<p>因為管線界定了各欄之間的邊界，表格的原始碼並不需要像上面例子中各欄之間保持直行對齊。所以，底下一樣是個完全合法（雖然醜陋）的管線表格：</p>
<pre><code>fruit| price
-----|-----:
apple|2.05
pear|1.37
orange|3.09</code></pre>
<p>管線表格的資料格不能包含如段落、清單之類的區塊元素，也不能包含複數行文字。</p>
<p>注意：Pandoc 也可以看得懂以下形式的管線表格，這是由 Emacs 的 orgtbl-mod 所繪製：</p>
<pre><code>| One | Two   |
|-----+-------|
| my  | table |
| is  | nice  |</code></pre>
<p>主要的差別在於以 <code>+</code> 取代了部分的 <code>|</code>。其他的 orgtbl 功能並未支援。如果要指定非預設的直行對齊形式，你仍然需要在上面的表格中自行加入冒號。</p>
<h2 id="文件標題區塊"><a href="#文件標題區塊">文件標題區塊</a></h2>
<p>（譯註：本節中提到的「標題」均指 Title，而非 Headers）</p>
<p><strong>Extension: <code>pandoc_title_block</code></strong></p>
<p>如果檔案以文件標題（Title）區塊開頭</p>
<pre><code>% title
% author(s) (separated by semicolons)
% date</code></pre>
<p>這部份將不會作為一般文字處理，而會以書目資訊的方式解析。（這可用在像是單一 LaTeX 或是 HTML 輸出文件的書名上。）這個區塊僅能包含標題，或是標題與作者，或是標題、作者與日期。如果你只想包含作者卻不想包含標題，或是只有標題與日期而沒有作者，你得利用空白行：</p>
<pre><code>%
% Author

% My title
%
% June 15, 2006</code></pre>
<p>標題可以包含多行文字，但接續行必須以空白字元開頭，像是：</p>
<pre><code>% My title
  on multiple lines</code></pre>
<p>如果文件有多個作者，作者也可以分列在不同行並以空白字元作開頭，或是以分號間隔，或是兩者並行。所以，下列各種寫法得到的結果都是相同的：</p>
<pre><code>% Author One
  Author Two

% Author One; Author Two

% Author One;
  Author Two</code></pre>
<p>日期就只能寫在一行之內。</p>
<p>所有這三個 metadata 欄位都可以包含標準的行內格式（斜體、連結、腳註等等）。</p>
<p>文件標題區塊一定會被分析處理，但只有在 <code>--standaline</code> (<code>-s</code>) 選項被設定時才會影響輸出內容。在輸出 HTML 時，文件標題會出現的地方有兩個：一個是在文件的 <code>&lt;head&gt;</code> 區塊裡－－這會顯示在瀏覽器的視窗標題上－－另外一個是文件的 <code>&lt;body&gt;</code> 區塊最前面。位於 <code>&lt;head&gt;</code> 裡的文件標題可以選擇性地加上前綴文字（透過 <code>--title-prefix</code> 或 <code>-T</code> 選項）。而在 <code>&lt;body&gt;</code> 裡的文件標題會以 H1 元素呈現，並附帶 “title” 類別 (class)，這樣就能藉由 CSS 來隱藏顯示或重新定義格式。如果以 <code>-T</code> 選項指定了標題前綴文字，卻沒有設定文件標題區塊裡的標題，那麼前綴文字本身就會被當作是 HTML 的文件標題。</p>
<p>而 man page 的輸出器會分析文件標題區塊的標題行，以解出標題、man page section number，以及其他頁眉 (header) 頁腳 (footer) 所需要的資訊。一般會假設標題行的第一個單字為標題，標題後也許會緊接著一個以括號包住的單一數字，代表 section number（標題與括號之間沒有空白）。在此之後的其他文字則為頁腳與頁眉文字。頁腳與頁眉文字之間是以單獨的一個管線符號 (<code>|</code>) 作為區隔。所以，</p>
<pre><code>% PANDOC(1)</code></pre>
<p>將會產生一份標題為 <code>PANDOC</code> 且 section 為 1 的 man page。</p>
<pre><code>% PANDOC(1) Pandoc User Manuals</code></pre>
<p>產生的 man page 會再加上 “Pandoc User Manuals” 在頁腳處。</p>
<pre><code>% PANDOC(1) Pandoc User Manuals | Version 4.0</code></pre>
<p>產生的 man page 會再加上 “Version 4.0” 在頁眉處。</p>
<h2 id="反斜線跳脫字元"><a href="#反斜線跳脫字元">反斜線跳脫字元</a></h2>
<p><strong>Extension: <code>all_symbols_escapable</code></strong></p>
<p>除了在代碼區塊或行內代碼之外，任何標點符號或空白字元前面只要加上一個反斜線，都能使其保留字面原義，而不會進行格式的轉義解讀。因此，舉例來說，下面的寫法</p>
<pre><code>*\*hello\**</code></pre>
<p>輸出後會得到</p>
<pre><code>&lt;em&gt;*hello*&lt;/em&gt;</code></pre>
<p>而不是</p>
<pre><code>&lt;strong&gt;hello&lt;/strong&gt;</code></pre>
<p>這條規則比原始的 markdown 規則來得好記許多，原始規則中，只有以下字元才有支援反斜線跳脫，不作進一步轉義：</p>
<pre><code>\`*_{}[]()&gt;#+-.!</code></pre>
<p>（然而，如果使用了 <code>markdown_strict</code> 格式，那麼就會採用原始的 markdown 規則）</p>
<p>一個反斜線之後的空白字元會被解釋為不斷行的空白 (nonbreaking space)。這在 TeX 的輸出中會顯示為 <code>~</code>，而在 HTML 與 XML 則是顯示為 <code>\&amp;#160;</code> 或 <code>\&amp;nbsp;</code>。</p>
<p>一個反斜線之後的換行字元（例如反斜線符號出現在一行的最尾端）則會被解釋為強制換行。這在 TeX 的輸出中會顯示為 <code>\\</code>，而在 HTML 裡則是 <code>&lt;br /&gt;</code>。相對於原始 markdown 是以在行尾加上兩個空白字元這種「看不見」的方式進行強制換行，反斜線接換行字元會是比較好的替代方案。</p>
<p>反斜線跳脫字元在代碼上下文中不起任何作用。</p>
<h2 id="智慧型標點符號"><a href="#智慧型標點符號">智慧型標點符號</a></h2>
<p><strong>Extension</strong></p>
<p>如果指定了 <code>--smart</code> 選項，pandoc 將會輸出正式印刷用的標點符號，像是將 straight quotes 轉換為 curly quotes<a href="#fn4" class="footnoteRef" id="fnref4"><sup>4</sup></a>、<code>---</code> 轉為破折號 (em-dashes)，<code>--</code> 轉為連接號 (en-dashes)，以及將 <code>...</code> 轉為刪節號。不斷行空格 (Nonbreaking spaces) 將會插入某些縮寫詞之後，例如 “Mr.”。</p>
<p>注意：如果你的 LaTeX template 使用了 <code>csquotes</code> 套件，pandoc 會自動偵測並且使用 <code>\enquote{...}</code> 在引言文字上。</p>
<h2 id="行內格式"><a href="#行內格式">行內格式</a></h2>
<h3 id="強調"><a href="#強調">強調</a></h3>
<p>要 <em>強調</em> 某些文字，只要以 <code>*</code> 或 <code>_</code> 符號前後包住即可，像這樣：</p>
<pre><code>This text is _emphasized with underscores_, and this
is *emphasized with asterisks*.</code></pre>
<p>重複兩個 <code>*</code> 或 <code>_</code> 符號以產生 <strong>更強烈的強調</strong>：</p>
<pre><code>This is **strong emphasis** and __with underscores__.</code></pre>
<p>一個前後以空白字元包住，或是前面加上反斜線的 <code>*</code> 或 <code>_</code> 符號，都不會轉換為強調格式：</p>
<pre><code>This is * not emphasized *, and \*neither is this\*.</code></pre>
<p><strong>Extension: <code>intraword_underscores</code></strong></p>
<p>因為 <code>_</code> 字元有時會使用在單字或是 ID 之中，所以 pandoc 不會把被字母包住的 <code>_</code> 解讀為強調標記。如果有需要特別強調單字中的一部分，就用 <code>*</code>：</p>
<pre><code>feas*ible*, not feas*able*.</code></pre>
<h3 id="刪除線"><a href="#刪除線">刪除線</a></h3>
<p><strong>Extension: <code>strikeout</code></strong></p>
<p>要將一段文字加上水平線作為刪除效果，將該段文字前後以 <code>~~</code> 包住即可。例如，</p>
<pre><code>This ~~is deleted text.~~</code></pre>
<h3 id="上標與下標"><a href="#上標與下標">上標與下標</a></h3>
<p><strong>Extension: <code>superscript</code>, <code>subscript</code></strong></p>
<p>要輸入上標可以用 <code>^</code> 字元將要上標的文字包起來；要輸入下標可以用 <code>~</code> 字元將要下標的文字包起來。直接看範例，</p>
<pre><code>H~2~O is a liquid.  2^10^ is 1024.</code></pre>
<p>如果要上標或下標的文字中包含了空白，那麼這個空白字元之前必須加上反斜線。（這是為了避免一般使用下的 <code>~</code> 和 <code>^</code> 在非預期的情況下產生出意外的上標或下標。）所以，如果你想要讓字母 P 後面跟著下標文字 ‘a cat’，那麼就要輸入 <code>P~a\ cat~</code>，而不是 <code>P~a cat~</code>。</p>
<h3 id="字面文字"><a href="#字面文字">字面文字</a></h3>
<p>要讓一小段文字直接以其字面形式呈現，可以用反引號將其包住：</p>
<pre><code>What is the difference between `&gt;&gt;=` and `&gt;&gt;`?</code></pre>
<p>如果字面文字中也包含了反引號，那就使用雙重反引號包住：</p>
<pre><code>Here is a literal backtick `` ` ``.</code></pre>
<p>（在起始反引號後的空白以及結束反引號前的空白都會被忽略。）</p>
<p>一般性的規則如下，字面文字區段是以連續的反引號字元作為開始（反引號後的空白字元為可選），一直到同樣數目的反引號字元出現才結束（反引號前的空白字元也為可選）。</p>
<p>要注意的是，反斜線跳脫字元（以及其他 markdown 結構）在字面文字的上下文中是沒有效果的：</p>
<pre><code>This is a backslash followed by an asterisk: `\*`.</code></pre>
<p><strong>Extension: <code>inline_code_attributes</code></strong></p>
<p>與<a href="#圍欄代碼區塊">圍欄代碼區塊</a>一樣，字面文字也可以附加屬性：</p>
<pre><code>`&lt;$&gt;`{.haskell}</code></pre>
<h2 id="數學"><a href="#數學">數學</a></h2>
<p><strong>Extension: <code>tex_math_dollars</code></strong></p>
<p>所有介於兩個 <code>$</code> 字元之間的內容將會被視為 TeX 數學公式處理。開頭的 <code>$</code> 右側必須立刻接上任意文字，而結尾 <code>$</code> 的左側同樣也必須緊挨著文字。這樣一來，<code>$20,000 and $30,000</code> 就不會被當作數學公式處理了。如果基於某些原因，有必須使用 <code>$</code> 符號將其他文字括住的需求時，那麼可以在 <code>$</code> 前使用反斜線跳脫字元，這樣 <code>$</code> 就不會被當作數學公式的分隔符。</p>
<p>TeX 數學公式會在所有輸出格式中印出。至於會以什麼方式演算編排 (render) 則取決於輸出的格式：</p>
<dl>
<dt>Markdown, LaTeX, Org-Mode, ConTeXt</dt>
<dd><p>公式會以字面文字呈現在兩個 <code>$</code> 符號之間。</p>
</dd>
<dt>reStructuredText</dt>
<dd><p>公式會使用 <a href="http://www.american.edu/econ/itex2mml/mathhack.rst">此處</a> 所描述的 <code>:math:</code> 這個 “interpreted text role” 來進行演算編排。</p>
</dd>
<dt>AsciiDoc</dt>
<dd><p>公式會以 <code>latexmath:[...]</code> 演算編排。</p>
</dd>
<dt>Texinfo</dt>
<dd><p>公式會在 <code>@math</code> 指令中演算編排。</p>
</dd>
<dt>groff man</dt>
<dd><p>公式會以去掉 <code>$</code> 後的字面文字演算編排。</p>
</dd>
<dt>MediaWiki</dt>
<dd><p>公式會在 <code>&lt;math&gt;</code> 標籤中演算編排。</p>
</dd>
<dt>Textile</dt>
<dd><p>公式會在 <code>&lt;span class=&quot;math&quot;&gt;</code> 標籤中演算編排。</p>
</dd>
<dt>RTF, OpenDocument, ODT</dt>
<dd><p>如果可以的話，公式會以 unicode 字元演算編排，不然就直接使用字面字元。</p>
</dd>
<dt>Docbook</dt>
<dd><p>如果使用了 <code>--mathml</code> 旗標，公式就會在 <code>inlineequation</code> 或 <code>informalequation</code> 標籤中使用 mathml 演算編排。否則就會盡可能使用 unicode 字元演算編排。</p>
</dd>
<dt>Docx</dt>
<dd><p>公式會以 OMML 數學標記的方式演算編排。</p>
</dd>
<dt>FictionBook2</dt>
<dd><p>如果有使用 <code>--webtex</code> 選項，公式會以 Google Charts 或其他相容的網路服務演算編排為圖片，並下載嵌入於電子書中。否則就會以字面文字顯示。</p>
</dd>
<dt>HTML, Slidy, DZSlides, S5, EPUB</dt>
<dd><p>公式會依照以下命令列選項的設置，以不同的方法演算編排為 HTML 代碼。</p>
<ol type="1">
<li><p>預設方式是將 TeX 數學公式盡可能地以 unicode 字元演算編排，如同 RTF、DocBook 以及 OpenDocument 的輸出。公式會被放在附有屬性 <code>class=&quot;math&quot;</code> 的 <code>span</code> 標籤內，所以可以在需要時給予不同的樣式，使其突出於周遭的文字內容。</p></li>
<li><p>如果使用了 <code>--latexmathml</code> 選項，TeX 數學公式會被顯示於 <code>$</code> 或 <code>$$</code> 字元中，並放在附帶 <code>LaTeX</code> 類別的 <code>&lt;span&gt;</code> 標籤裡。這段內容會用 <a href="http://math.etsu.edu/LaTeXMathML/">LaTeXMathML</a> script 演算編排為數學公式。（這個方法無法適用於所有瀏覽器，但在 Firefox 中是有效的。在不支援 LaTeXMathML 的瀏覽器中，TeX 數學公式會單純的以兩個 <code>$</code> 字元間的字面文字呈現。）</p></li>
<li><p>如果使用了 <code>--jsmath</code> 選項，TeX數學公式會放在 <code>&lt;span&gt;</code> 標籤（用於行內數學公式）或 <code>&lt;div&gt;</code> 標籤（用於區塊數學公式）中，並附帶類別屬性 <code>math</code>。這段內容會使用 <a href="http://www.math.union.edu/~dpvc/jsmath/">jsMath</a> script 來演算編排。</p></li>
<li><p>如果使用了 <code>--mimetex</code> 選項，<a href="http://www.forkosh.com/mimetex.html">mimeTeX</a> CGI script 會被呼叫來產生每個 TeX 數學公式的圖片。這適用於所有瀏覽器。<code>--mimetex</code> 選項有一個可選的 URL 參數。如果沒有指定 URL，它會假設 mimeTeX CGI script 的位置在 <code>/cgi-bin/mimetex.cig</code>。</p></li>
<li><p>如果使用了 <code>--gladtex</code> 選項，TeX 數學公式在 HTML 的輸出中會被 <code>&lt;eq&gt;</code> 標籤包住。產生的 <code>htex</code> 檔案之後可以透過 <a href="http://ans.hsh.no/home/mgg/gladtex/">gladTeX</a> 處理，這會針對每個數學公式生成圖片，並於最後生成一個包含這些圖片連結的 <code>html</code> 檔案。所以，整個處理流程如下：</p>
<pre><code>pandoc -s --gladtex myfile.txt -o myfile.htex
gladtex -d myfile-images myfile.htex
# produces myfile.html and images in myfile-images</code></pre></li>
<li><p>如果使用了 <code>--webtex</code> 選項，TeX 數學公式會被轉換為 <code>&lt;img&gt;</code> 標籤並連結到一個用以轉換公式為圖片的外部 script。公式將會編碼為 URL 可接受格式並且與指定的 URL 參數串接。如果沒有指定 URL，那麼將會使用 Google Chart API (<code>http://chart.apis.google.com/chart?cht=tx&amp;chl=</code>)。</p></li>
<li><p>如果使用了 <code>--mathjax</code> 選項，TeX 數學公式將會被包在 <code>\(...\)</code>（用於行內數學公式）或 <code>\[...\]</code>（用於區塊數學公式）之間顯示，並且放在附帶類別 <code>math</code> 的 <code>&lt;span&gt;</code> 標籤之中。這段內容會使用 <a href="http://www.mathjax.org/">MathJax</a> script 演算編排為頁面上的數學公式。</p></li>
</ol>
</dd>
</dl>
<h2 id="raw-html"><a href="#raw-html">Raw HTML</a></h2>
<p><strong>Extension: <code>raw_html</code></strong></p>
<p>Markdown 允許你在文件中的任何地方插入原始 HTML（或 DocBook）指令（除了在字面文字上下文處，此時的 <code>&lt;</code>, <code>&gt;</code> 和 <code>&amp;</code> 都會按其字面意義顯示）。（技術上而言這不算擴充功能，因為原始 markdown 本身就有提供此功能，但做成擴充形式便可以在有特殊需要的時候關閉此功能。）</p>
<p>輸出 HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown 以及 Textile 等格式時，原始 HTML 代碼會不作修改地保留至輸出檔案中；而其他格式的輸出內容則會將原始 HTML 代碼去除掉。</p>
<p><strong>Extension: <code>markdown_in_html_blocks</code></strong></p>
<p>原始 markdown 允許你插入 HTML「區塊」：所謂的 HTML 區塊是指，上下各由一個空白行所隔開，開始與結尾均由所在行最左側開始的一連串對稱均衡的 HTML 標籤。在這個區塊中，任何內容都會當作是 HTML 來分析，而不再視為 markdown；所以（舉例來說），<code>*</code> 符號就不再代表強調。</p>
<p>當指定格式為 <code>markdown_strict</code> 時，Pandoc 會以上述方式處理；但預設情況下，Pandoc 能夠以 markdown 語法解讀 HTML 區塊標籤中的內容。舉例說明，Pandoc 能夠將底下這段</p>
<pre><code>&lt;table&gt;
    &lt;tr&gt;
        &lt;td&gt;*one*&lt;/td&gt;
        &lt;td&gt;[a link](http://google.com)&lt;/td&gt;
    &lt;/tr&gt;
&lt;/table&gt;</code></pre>
<p>轉換為</p>
<pre><code>&lt;table&gt;
    &lt;tr&gt;
        &lt;td&gt;&lt;em&gt;one&lt;/em&gt;&lt;/td&gt;
        &lt;td&gt;&lt;a href=&quot;http://google.com&quot;&gt;a link&lt;/a&gt;&lt;/td&gt;
    &lt;/tr&gt;
&lt;/table&gt;</code></pre>
<p>而 <code>Markdown.pl</code> 則是保留該段原樣。</p>
<p>這個規則只有一個例外：那就是介於 <code>&lt;script&gt;</code> 與 <code>&lt;style&gt;</code> 之間的文字都不會被拿來當作 markdown 解讀。</p>
<p>這邊與原始 markdown 的分歧，主要是為了讓 markdown 能夠更便利地混入 HTML 區塊元素。比方說，一段 markdown 文字可以用 <code>&lt;div&gt;</code> 標籤將其前後包住來進行樣式指定，而不用擔心裡面的 markdown 不會被解譯到。</p>
<h2 id="raw-tex"><a href="#raw-tex">Raw TeX</a></h2>
<p><strong>Extension: <code>raw_tex</code></strong></p>
<p>除了 HTML 之外，pandoc 也接受文件中嵌入原始 LaTeX, TeX 以及 ConTeXt 代碼。行內 TeX 指令會被保留並不作修改地輸出至 LaTeX 與 ConTeXt 格式中。所以，舉例來說，你可以使用 LaTeX 來導入 BibTeX 的引用文獻：</p>
<pre><code>This result was proved in \cite{jones.1967}.</code></pre>
<p>請注意在 LaTeX 環境下時，像是底下</p>
<pre><code>\begin{tabular}{|l|l|}\hline
Age &amp; Frequency \\ \hline
18--25  &amp; 15 \\
26--35  &amp; 33 \\
36--45  &amp; 22 \\ \hline
\end{tabular}</code></pre>
<p>位在 <code>begin</code> 與 <code>end</code> 標籤之間的內容，都會被當作是原始 LaTeX 資料解讀，而不會視為 markdown。</p>
<p>行內 LaTeX 在輸出至 Markdown, LaTeX 及 ConTeXt 之外的格式時會被忽略掉。</p>
<h2 id="latex-巨集"><a href="#latex-巨集">LaTeX 巨集</a></h2>
<p><strong>Extension: <code>latex_macros</code></strong></p>
<p>當輸出格式不是 LaTeX 時，pandoc 會分析 LaTeX 的 <code>\newcommand</code> 和 <code>\renewcommand</code> 定義，並套用其產生的巨集到所有 LaTeX 數學公式中。所以，舉例來說，下列指令對於所有的輸出格式均有作用，而非僅僅作用於 LaTeX 格式：</p>
<pre><code>\newcommand{\tuple}[1]{\langle #1 \rangle}

$\tuple{a, b, c}$</code></pre>
<p>在 LaTeX 的輸出中，<code>\newcommand</code> 定義會單純不作修改地保留至輸出結果。</p>
<h2 id="連結"><a href="#連結">連結</a></h2>
<p>Markdown 接受以下數種指定連結的方式。</p>
<h3 id="自動連結"><a href="#自動連結">自動連結</a></h3>
<p>如果你用角括號將一段 URL 或是 email 位址包起來，它會自動轉換成連結：</p>
<pre><code>&lt;http://google.com&gt;
&lt;sam@green.eggs.ham&gt;</code></pre>
<h3 id="行內連結"><a href="#行內連結">行內連結</a></h3>
<p>一個行內連結包含了位在方括號中的連結文字，以及方括號後以圓括號包起來的 URL。（你可以選擇性地在 URL 後面加入連結標題，標題文字要放在引號之中。）</p>
<pre><code>This is an [inline link](/url), and here&#39;s [one with
a title](http://fsf.org &quot;click here for a good time!&quot;).</code></pre>
<p>方括號與圓括號之間不能有空白。連結文字可以包含格式（例如強調），但連結標題則否。</p>
<h3 id="參考連結"><a href="#參考連結">參考連結</a></h3>
<p>一個 <strong>明確</strong> 的參考連結包含兩個部分，連結本身以及連結定義，其中連結定義可以放在文件的任何地方（不論是放在連結所在處之前或之後）。</p>
<p>連結本身是由兩組方括號所組成，第一組方括號中為連結文字，第二組為連結標籤。（在兩個方括號間可以有空白。）連結定義則是以方括號框住的連結標籤作開頭，後面跟著一個冒號一個空白，再接著一個 URL，最後可以選擇性地（在一個空白之後）加入由引號或是圓括號包住的連結標題。</p>
<p>以下是一些範例：</p>
<pre><code>[my label 1]: /foo/bar.html  &quot;My title, optional&quot;
[my label 2]: /foo
[my label 3]: http://fsf.org (The free software foundation)
[my label 4]: /bar#special  &#39;A title in single quotes&#39;</code></pre>
<p>連結的 URL 也可以選擇性地以角括號包住：</p>
<pre><code>[my label 5]: &lt;http://foo.bar.baz&gt;</code></pre>
<p>連結標題可以放在第二行：</p>
<pre><code>[my label 3]: http://fsf.org
  &quot;The free software foundation&quot;</code></pre>
<p>需注意連結標籤並不區分大小寫。所以下面的例子會建立合法的連結：</p>
<pre><code>Here is [my link][FOO]

[Foo]: /bar/baz</code></pre>
<p>在一個 <strong>隱性</strong> 參考連結中，第二組方括號的內容是空的，甚至可以完全地略去：</p>
<pre><code>See [my website][], or [my website].

[my website]: http://foo.bar.baz</code></pre>
<p>注意：在 <code>Markdown.pl</code> 以及大多數其他 markdown 實作中，參考連結的定義不能存在於嵌套結構中，例如清單項目或是區塊引言。Pandoc lifts this arbitrary seeming restriction。所以雖然下面的語法在幾乎所有其他實作中都是錯誤的，但在 pandoc 中可以正確處理：</p>
<pre><code>&gt; My block [quote].
&gt;
&gt; [quote]: /foo</code></pre>
<h3 id="內部連結"><a href="#內部連結">內部連結</a></h3>
<p>要連結到同一份文件的其他章節，可使用自動產生的 ID（參見 <a href="#html-latex-與-context-的標題識別符">HTML, LaTeX 與 ConTeXt 的標題識別符</a> 一節後半）。例如：</p>
<pre><code>See the [Introduction](#introduction).</code></pre>
<p>或是</p>
<pre><code>See the [Introduction].

[Introduction]: #introduction</code></pre>
<p>內部連結目前支援的格式有 HTML（包括 HTML slide shows 與 EPUB）、LaTeX 以及 ConTeXt。</p>
<h2 id="圖片"><a href="#圖片">圖片</a></h2>
<p>在連結語法的前面加上一個 <code>!</code> 就是圖片的語法了。連結文字將會作為圖片的替代文字（alt text）：</p>
<pre><code>![la lune](lalune.jpg &quot;Voyage to the moon&quot;)

![movie reel]

[movie reel]: movie.gif</code></pre>
<h3 id="附上說明的圖片"><a href="#附上說明的圖片">附上說明的圖片</a></h3>
<p><strong>Extension: <code>implicit_figures</code></strong></p>
<p>一個圖片若自身單獨存在一個段落中，那麼將會以附上圖片說明 (caption) 的圖表 (figure) 形式呈現。<a href="#fn5" class="footnoteRef" id="fnref5"><sup>5</sup></a>（在 LaTeX 中，會使用圖表環境；在 HTML 中，圖片會被放在具有 <code>figure</code> 類別的 <code>div</code> 元素中，並會附上一個具有 <code>caption</code> 類別的 <code>p</code> 元素。）圖片的替代文字同時也會用來作為圖片說明。</p>
<pre><code>![This is the caption](/url/of/image.png)</code></pre>
<p>如果你只是想要個一般的行內圖片，那麼只要讓圖片不是段落裡唯一的元素即可。一個簡單的方法是在圖片後面插入一個不斷行空格：</p>
<pre><code>![This image won&#39;t be a figure](/url/of/image.png)\</code></pre>
<h2 id="腳註"><a href="#腳註">腳註</a></h2>
<p><strong>Extension: <code>footnotes</code></strong></p>
<p>Pandoc’s markdown 支援腳註功能，使用以下的語法：</p>
<pre><code>Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here&#39;s one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won&#39;t be part of the note, because it
isn&#39;t indented.</code></pre>
<p>腳註參考用的 ID 不得包含空白、tabs 或換行字元。這些 ID 只會用來建立腳註位置與腳註文字的對應關連；在輸出時，腳註將會依序遞增編號。</p>
<p>腳註本身不需要放在文件的最後面。它們可以放在文件裡的任何地方，但不能被放入區塊元素（清單、區塊引言、表格等）之中。</p>
<p><strong>Extension: <code>inline_notes</code></strong></p>
<p>Pandoc 也支援了行內腳註（儘管，與一般腳註不同，行內腳註不能包含多個段落）。其語法如下：</p>
<pre><code>Here is an inline note.^[Inlines notes are easier to write, since
you don&#39;t have to pick an identifier and move down to type the
note.]</code></pre>
<p>行內與一般腳註可以自由交錯使用。</p>
<h2 id="引用"><a href="#引用">引用</a></h2>
<p><strong>Extension: <code>citations</code></strong></p>
<p>Pandoc 能夠以數種形式自動產生引用與參考書目（使用 Andrea Rossato 的 <code>hs-citeproc</code>）。為了使用這項功能，你需要一個下列其中一種格式的參考書目資料庫：</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Format</th>
<th style="text-align: left;">File extension</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">MODS</td>
<td style="text-align: left;">.mods</td>
</tr>
<tr class="even">
<td style="text-align: left;">BibLaTeX</td>
<td style="text-align: left;">.bib</td>
</tr>
<tr class="odd">
<td style="text-align: left;">BibTeX</td>
<td style="text-align: left;">.bibtex</td>
</tr>
<tr class="even">
<td style="text-align: left;">RIS</td>
<td style="text-align: left;">.ris</td>
</tr>
<tr class="odd">
<td style="text-align: left;">EndNote</td>
<td style="text-align: left;">.enl</td>
</tr>
<tr class="even">
<td style="text-align: left;">EndNote XML</td>
<td style="text-align: left;">.xml</td>
</tr>
<tr class="odd">
<td style="text-align: left;">ISI</td>
<td style="text-align: left;">.wos</td>
</tr>
<tr class="even">
<td style="text-align: left;">MEDLINE</td>
<td style="text-align: left;">.medline</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Copac</td>
<td style="text-align: left;">.copac</td>
</tr>
<tr class="even">
<td style="text-align: left;">JSON citeproc</td>
<td style="text-align: left;">.json</td>
</tr>
</tbody>
</table>
<p>需注意的是副檔名 <code>.bib</code> 一般而言同時適用於 BibTeX 與 BibLaTeX 的檔案，不過你可以使用 <code>.bibtex</code> 來強制指定 BibTeX。</p>
<p>你需要使用命令列選項 <code>--bibliography</code> 來指定參考書目檔案（如果有多個書目檔就得反覆指定）。</p>
<p>預設情況下，pandoc 會在引用文獻與參考書目中使用芝加哥「作者－日期」格式。要使用其他的格式，你需要用 <code>--csl</code> 選項來指定一個 <a href="http://CitationStyles.org">CSL</a> 1.0 格式的檔案。關於建立與修改 CSL 格式的入門可以在 <a href="http://citationstyles.org/downloads/primer.html">http://citationstyles.org/downloads/primer.html</a> 這邊找到。<a href="https://github.com/citation-style-language/styles">https://github.com/citation-style-language/styles</a> 是 CSL 格式的檔案庫。也可以在 <a href="http://zotero.org/styles">http://zotero.org/styles</a> 以簡單的方式瀏覽。</p>
<p>引用資訊放在方括號中，以分號區隔。每一條引用都會有個 key，由 <code>@</code> 加上資料庫中的引用 ID 組成，並且可以選擇性地包含前綴、定位以及後綴。以下是一些範例：</p>
<pre><code>Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].</code></pre>
<p>在 <code>@</code> 前面的減號 (<code>-</code>) 將會避免作者名字在引用中出現。這可以用在已經提及作者的文章場合中：</p>
<pre><code>Smith says blah [-@smith04].</code></pre>
<p>你也可以在文字中直接插入引用資訊，方式如下：</p>
<pre><code>@smith04 says blah.

@smith04 [p. 33] says blah.</code></pre>
<p>如果引用格式檔需要產生一份引用作品的清單，這份清單會被放在文件的最後面。一般而言，你需要以一個適當的標題結束你的文件：</p>
<pre><code>last paragraph...

# References</code></pre>
<p>如此一來參考書目就會被放在這個標題後面了。</p>
<section class="footnotes">
<hr />
<ol>
<li id="fn1"><p>之所以有這條規則，主要是要避免以人名頭文字縮寫作為開頭的段落所帶來的混淆，像是</p>
<pre><code>B. Russell was an English philosopher.</code></pre>
<p>這樣就不會被當作清單項目了。</p>
<p>這條規則並不會避免以下</p>
<pre><code>(C) 2007 Joe Smith</code></pre>
<p>這樣的敘述被解釋成清單項目。在這情形下，可以使用反斜線：</p>
<pre><code>(C\) 2007 Joe Smith</code></pre>
<a href="#fnref1">↩</a></li>
<li id="fn2"><p><a href="http://www.justatheory.com/computers/markup/modest-markdown-proposal.html">David Wheeler</a> 對於 markdown 的建議也同時影響了我。<a href="#fnref2">↩</a></p></li>
<li id="fn3"><p>這個方案是由 Michel Fortin 在 <a href="http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html">Markdown discussion list</a> 的討論中所提出。<a href="#fnref3">↩</a></p></li>
<li id="fn4"><p>譯註：straight quotes 指的是左右兩側都長得一樣的引號，例如我們直接在鍵盤上打出來的單引號或雙引號；curly quotes 則是左右兩側不同，有從兩側向內包夾視覺效果的引號。<a href="#fnref4">↩</a></p></li>
<li id="fn5"><p>這項功能尚未在 RTF, OpenDocument 或 ODT 格式上實現。在這些格式中，你會得到一個在段落中只包含自己的圖片，而無圖片說明。<a href="#fnref5">↩</a></p></li>
</ol>
</section>
<hr>
<!-- disqus begin -->
<div id="disqus_thread"></div>
  <script type="text/javascript">
    var disqus_shortname = 'tzyxpages'; // required: replace example with your forum shortname
    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
      var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
      dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
      (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
  </script>
  <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
  <a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div>
<!-- disqus end -->
<!-- google analytics begin -->
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-23745502-8', 'tzengyuxio.me');
  ga('send', 'pageview');

</script>
<!-- google analytics end -->
</div><!--/row-->
</div><!--/container-->
</body>
</html>
